Scripting
Getting Started
Documentation
Changelog
Privacy
Getting Started
Documentation
Changelog
Privacy

HealthWorkout

The HealthWorkout class provides a high-level interface for accessing and analyzing workout data from Apple Health. A workout represents a full session of physical activity, such as running, swimming, or cycling, recorded between a start and end time, and may include additional events and aggregated statistics.

Use Cases

  • Retrieve and display workout history
  • Analyze workout types and durations
  • Correlate workout sessions with metrics such as heart rate, calories burned, or distance
  • Visualize workout events like pauses, resumes, laps, and segments
  • Access health statistics collected during the workout session

Properties

Property Type Description
uuid string A unique identifier for the workout instance.
workoutActivityType HealthWorkoutActivityType The type of activity, such as running, swimming, yoga, etc.
startDate Date The start time of the workout session.
endDate Date The end time of the workout session.
duration number The duration of the workout in seconds.
metadata Record<string, any> | null Optional metadata, which may include the source app, device, or user-defined tags.
workoutEvents HealthWorkoutEvent[] | null An array of workout events such as pauses, laps, or segments, captured during the session.
allStatistics Record<HealthQuantityType, HealthStatistics | null> A dictionary mapping quantity types to statistics recorded during the workout (e.g. heart rate).

Related Types

HealthWorkoutActivityType

Represents the type of physical activity, such as:

  • running
  • walking
  • cycling
  • swimming
  • yoga
  • ... and many more (see HealthWorkoutActivityType documentation)

HealthWorkoutEvent

Represents a specific event during the workout, such as:

  • pause
  • resume
  • motion paused/resumed
  • lap or segment markers

HealthStatistics

Provides calculated metrics such as:

  • averageQuantity()
  • sumQuantity()
  • maximumQuantity()
  • minimumQuantity()
  • mostRecentQuantity()

These are based on health data samples (e.g., heart rate, energy burned) during the workout's time interval.

Example Usage

1function displayWorkoutSummary(workout: HealthWorkout) {
2  console.log(`Workout ID: ${workout.uuid}`)
3  console.log(`Activity Type: ${workout.workoutActivityType}`)
4  console.log(`Start: ${workout.startDate.toISOString()}`)
5  console.log(`End: ${workout.endDate.toISOString()}`)
6  console.log(`Duration: ${(workout.duration / 60).toFixed(1)} minutes`)
7
8  if (workout.metadata) {
9    console.log(`Metadata: ${JSON.stringify(workout.metadata)}`)
10  }
11
12  if (workout.workoutEvents) {
13    for (const event of workout.workoutEvents) {
14      console.log(`Event: ${HealthWorkoutEventType[event.type]} at ${event.dateInterval.start.toISOString()}`)
15    }
16  }
17
18  const heartRateStats = workout.allStatistics["heartRate"]
19  if (heartRateStats) {
20    console.log(`Average Heart Rate: ${heartRateStats.averageQuantity("count/min")} bpm`)
21  }
22}

Notes

  • HealthWorkout instances are typically retrieved using query APIs such as Health.queryWorkouts() (if available in the framework).
  • The allStatistics property provides quick access to summary data without needing to query samples manually.
  • Use the workoutEvents property to reconstruct the timeline of activity (e.g., when the user paused or resumed).
Outline